Merge branch 'main' into codex/lyrics-style-format-fallback

Author: riversedge

.github/copilot-instructions.md

@@ -146,17 +146,10 @@ jobs:
           -srcfolder dmg_temp \
           -ov -format UDZO \
           AceForge-macOS.dmg
-          
-    - name: Create ZIP archive (alternative distribution)
-      run: |
-        cd dist
-        zip -r ../AceForge-macOS.zip AceForge.app
-        cd ..
         
     - name: Calculate checksums
       run: |
         shasum -a 256 AceForge-macOS.dmg > checksums.txt
-        shasum -a 256 AceForge-macOS.zip >> checksums.txt
         cat checksums.txt
         
     - name: Upload DMG artifact
@@ -171,5 +164,4 @@ jobs:
       with:
         files: |
           AceForge-macOS.dmg
-          AceForge-macOS.zip
           checksums.txt

.github/workflows/build-release.yml

@@ -61,6 +61,24 @@ AceForge is a **local-first AI music workstation for macOS Silicon** powered by
 
 > **Note:** The app bundle does NOT include the large model files. On first run, it will download the ACE-Step models (several GB) automatically. You can monitor the download progress in the Terminal window or in the Server Console panel in the web interface.
 
+### Option 2: Run locally for testing (developers)
+
+To run the app from source without building the `.app` bundle:
+
+1. **One-time setup:** Install dependencies (e.g. run the full build once to create the venv):
+   ```bash
+   ./build_local.sh
+   ```
+   This creates `venv_build/` and installs Python deps. You can cancel after the PyInstaller step if you only want to run locally.
+
+2. **Run the server:**
+   ```bash
+   ./run_local.sh
+   ```
+   This builds the React UI if needed (requires [Bun](https://bun.sh)), then starts the Flask server at **http://127.0.0.1:5056**. Open that URL in your browser to use AceForge.
+
+If you prefer to use your own venv instead of `venv_build`, install deps with `pip install -r requirements_ace_macos.txt` (and the same extra steps as in `build_local.sh` for TTS/ACE-Step), then run `python music_forge_ui.py`.
+
 ## Using AceForge (high-level workflow)
 
 1. Launch AceForge and wait for the UI

README.md

@@ -1355,7 +1355,7 @@ def text2music_diffusion_process(
         use_erg_lyric=False,
         use_erg_diffusion=False,
         retake_random_generators=None,
-        retake_variance=0.5,
+        retake_variance=0.2,
         add_retake_noise=False,
         guidance_scale_text=0.0,
         guidance_scale_lyric=0.0,
@@ -2052,7 +2052,7 @@ def __call__(
         lora_name_or_path: str = "none",
         lora_weight: float = 1.0,
         retake_seeds: list = None,
-        retake_variance: float = 0.5,
+        retake_variance: float = 0.2,  # ACE-Step-MCP retake/repaint default
         task: str = "text2music",
         repaint_start: int = 0,
         repaint_end: int = 0,
@@ -2195,23 +2195,38 @@ def __call__(
         preprocess_time_cost = end_time - start_time
         start_time = end_time
 
+        # Lego/extract/complete: generate NEW track from prompt only; use source only for duration (no repaint/retake).
+        # Repaint/retake/extend: use src_latents in diffusion.
         add_retake_noise = task in ("retake", "repaint", "extend")
         # retake equal to repaint
         if task == "retake":
             repaint_start = 0
             repaint_end = audio_duration
+        if task in ("lego", "extract", "complete"):
+            repaint_start = 0
+            repaint_end = audio_duration
 
         src_latents = None
         if src_audio_path is not None:
             assert src_audio_path is not None and task in (
                 "repaint",
                 "edit",
                 "extend",
-            ), "src_audio_path is required for retake/repaint/extend task"
+                "lego",
+                "extract",
+                "complete",
+            ), "src_audio_path is required for repaint/extend/lego/extract/complete task"
             assert os.path.exists(
                 src_audio_path
             ), f"src_audio_path {src_audio_path} does not exist"
-            src_latents = self.infer_latents(src_audio_path)
+            src_latents_inferred = self.infer_latents(src_audio_path)
+            if task in ("lego", "extract", "complete"):
+                # Use source only to set output duration; do not pass latents into diffusion (generate from scratch with prompt).
+                num_frames = src_latents_inferred.shape[-1]
+                audio_duration = num_frames * 512 * 8 / 44100.0
+                src_latents = None  # no repaint for lego
+            else:
+                src_latents = src_latents_inferred
 
         ref_latents = None
         if ref_audio_input is not None and audio2audio_enable:

api/generate.py

@@ -3,6 +3,11 @@
   Source: https://github.com/ace-step/ACE-Step-1.5/blob/main/docs/en/INFERENCE.md
   Use for: GenerationParams/GenerationConfig, task types (text2music, cover, repaint, etc.),
   reference_audio vs src_audio, audio_cover_strength, and parameter specs.
+
+  AceForge alignment: We align core defaults with the working ACE-Step-MCP reference
+  (https://huggingface.co/spaces/reach-vb/ACE-Step-MCP/blob/main/ui/components.py):
+  ref_audio_strength=0.5 (Audio2Audio/cover reference), retake_variance=0.2 (retake/repaint),
+  and pipeline param names ref_audio_input, src_audio_path, audio2audio_enable.
 -->
 
 # ACE-Step Inference API Documentation

cdmf_pipeline_ace_step.py

@@ -125,16 +125,21 @@ ACE-Step text-to-music (and related tasks). Jobs are queued and run one at a tim
 - `inferenceSteps`: int (e.g. 55).
 - `guidanceScale`: float (e.g. 6.0).
 - `seed`: int; if `randomSeed` is true, server may override with random.
-- `taskType`: `"text2music"` | `"retake"` | `"repaint"` | `"extend"` | `"cover"` | `"audio2audio"`.
-- `referenceAudioUrl`, `sourceAudioUrl`: URLs like `/audio/refs/...` or `/audio/<filename>` for reference/cover.
-- `audioCoverStrength` / `ref_audio_strength`: 0–1.
-- `repaintingStart`, `repaintingEnd`: for repaint task.
+- **Task and audio params** (see [ACE-Step Tutorial](https://github.com/ace-step/ACE-Step-1.5/blob/main/docs/en/Tutorial.md#guiding-the-elephant-what-can-you-control)): The API accepts both **ACE-Step official names** (snake_case) and **UI names** (camelCase): `task_type` or `taskType`; `reference_audio` or `referenceAudioUrl` or `reference_audio_path`; `src_audio` or `sourceAudioUrl` or `source_audio_path`; `audio_cover_strength` or `audioCoverStrength` or `ref_audio_strength`.
+- `taskType` / `task_type`: `"text2music"` | `"retake"` | `"repaint"` | `"extend"` | `"cover"` | `"audio2audio"` | `"lego"` | `"extract"` | `"complete"`. **Lego**, **extract**, and **complete** require the ACE-Step **Base** DiT model (see Preferences and ACE-Step models).
+- `instruction`: optional; for **lego** (and extract/complete), task-specific instruction (e.g. `"Generate the guitar track based on the audio context:"`). If omitted for lego, the server builds one from track name/caption.
+- `reference_audio` / `referenceAudioUrl`: path or URL for reference audio (style/timbre). `src_audio` / `sourceAudioUrl`: path or URL for source/backing audio (cover, repaint, lego, etc.). For **lego**, **extract**, and **complete**, source audio is required.
+- `audio_cover_strength` / `audioCoverStrength`: 0–1 (reference/source influence strength). Defaults: **cover/retake** 0.8 (strong source); **audio2audio** 0.5 (matches [ACE-Step-MCP](https://huggingface.co/spaces/reach-vb/ACE-Step-MCP)); **lego** uses `legoBackingInfluence` (default 0.25).
+- `retake_variance` / `retakeVariance`: 0–1, default 0.2 (retake/repaint; aligned with ACE-Step-MCP).
+- `repaintingStart`, `repaintingEnd` / `repaint_start`, `repaint_end`: for repaint task; -1 end = end of audio.
 - `title`: base name for output file.
 - `outputDir` / `output_dir`: optional; else uses app default.
 - `keyScale`, `timeSignature`, `vocalLanguage`, `bpm`: optional.
 - `loraNameOrPath`: optional; folder name from LoRA list or path to adapter (see `GET /api/generate/lora_adapters`).
 - `loraWeight`: optional; 0–2, default 0.75.
 
+**Base-only tasks (lego, extract, complete):** Require `ace_step_dit_model: "base"` in preferences and the Base model to be installed (Settings or `GET /api/ace-step/models`). For **lego**: send `taskType: "lego"`, `sourceAudioUrl` (backing audio), `instruction` (e.g. `"Generate the <track> track based on the audio context:"`), and `style` as the track description (caption). Supported track names: `vocals`, `backing_vocals`, `drums`, `bass`, `guitar`, `keyboard`, `percussion`, `strings`, `synth`, `fx`, `brass`, `woodwinds`. See `docs/ACE-Step-INFERENCE.md` for extract/complete parameters.
+
 **Response (POST):** `{ "jobId": "<uuid>", "status": "queued", "queuePosition": 1 }`
 
 **Status response:** `{ "jobId", "status": "queued"|"running"|"succeeded"|"failed"|"cancelled", "queuePosition"?, "etaSeconds"?, "result"?, "error"? }`. On success, `result` includes e.g. `audioUrls`, `duration`, `status`. Cancelled jobs have `status: "cancelled"` and `error: "Cancelled by user"`.
@@ -203,11 +208,12 @@ List available DiT/LM models and trigger downloads. **The ACE-Step 1.5 downloade
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/ace-step/models` | List DiT and LM models with `installed` status, plus `discovered_models`: all model directories found under the checkpoints folder (including custom trained models). Response includes `dit_models`, `lm_models`, `discovered_models` (id, label, path, custom), `acestep_download_available`, `checkpoints_path`. |
-| POST | `/api/ace-step/models/download` | Start download. Body: `{ "model": "turbo" | "turbo-shift1" | "sft" | "base" | "0.6B" | "1.7B" | "4B" }`. Uses bundled downloader (or `acestep-download` on PATH if not bundled). Returns `{ "ok", "model", "path" }` or `{ "error", "hint" }`. |
-| GET | `/api/ace-step/models/status` | Download progress: `{ "running", "model", "progress", "error" }`. |
+| GET | `/api/ace-step/models` | List DiT and LM models with `installed` status, plus `discovered_models`: all model directories found under the checkpoints folder (including custom trained models). Response includes `dit_models`, `lm_models`, `discovered_models` (id, label, path, custom), `acestep_download_available`, `checkpoints_path`. Use this to verify the **Base** model is installed before starting a lego/extract/complete job. |
+| POST | `/api/ace-step/models/download` | Start download. Body: `{ "model": "turbo" \| "turbo-shift1" \| "turbo-shift3" \| "turbo-continuous" \| "sft" \| "base" \| "0.6B" \| "1.7B" \| "4B" }`. Uses bundled downloader (or `acestep-download` on PATH if not bundled). Returns `{ "ok", "model", "path" }` or `{ "error", "hint" }`. |
+| GET | `/api/ace-step/models/status` | Download progress: `{ "running", "model", "progress", "error", "current_file", "file_index", "total_files", "eta_seconds", "cancelled" }`. |
+| POST | `/api/ace-step/models/download/cancel` | Request cancellation of the current download. Returns `{ "cancelled", "message" }`. |
 
-**Task types:** Generation accepts `taskType`: `text2music`, `cover`, `audio2audio`, `repaint`, `extend`, and (ACE-Step 1.5 Base) `lego`, `extract`, `complete`. Lego/extract/complete require the Base model and full 1.5 integration (planned).
+**Task → model:** Generation accepts `taskType`: `text2music`, `cover`, `audio2audio`, `repaint`, `extend`, and (Base-only) `lego`, `extract`, `complete`. **Lego**, **extract**, and **complete** require the **Base** DiT model: set `ace_step_dit_model` to `"base"` in preferences and ensure the Base model is installed (download via Settings or `POST /api/ace-step/models/download` with `"model": "base"`). The UI checks `GET /api/ace-step/models` for `dit_models[].installed` before allowing these tasks.
 
 ---
 

docs/ACE-Step-INFERENCE.md

@@ -567,9 +567,9 @@ def _prepare_reference_audio(
     src_audio_path: str | None,
 ) -> tuple[str, bool, Optional[str]]:
     """
-    Normalise the ACE-Step edit / audio2audio mode:
+    Normalise the ACE-Step edit / audio2audio mode (task_type, reference_audio, src_audio per Tutorial/INFERENCE):
 
-      - Task is clamped to one of: text2music / retake / repaint / extend.
+      - Task (task_type) is clamped to one of: text2music / retake / repaint / extend.
       - UI tasks "cover" and "audio2audio" are mapped to "retake" (ACE-Step
         then uses ref_audio_input and sets task to "audio2audio" internally).
       - If Audio2Audio is enabled while task is still 'text2music', we
@@ -592,15 +592,18 @@ def _prepare_reference_audio(
     if audio2audio_enable and task_norm == "text2music":
         task_norm = "retake"
 
-    # Any of the edit-style tasks imply some form of Audio2Audio.
+    # Any of the edit-style tasks imply some form of Audio2Audio or source-backed (lego/extract/complete).
     audio2audio_flag = bool(
         audio2audio_enable or task_norm in ("retake", "repaint", "extend")
     )
+    needs_src_path = audio2audio_flag or task_norm in ("lego", "extract", "complete")
 
-    # If we *think* we're in an edit / audio2audio mode but there's no
-    # reference audio path at all, don't crash — just fall back to
-    # plain text2music.
-    if audio2audio_flag and not src_audio_path:
+    # If we need source/reference audio but none was provided, fall back to text2music (or fail for lego/extract/complete).
+    if needs_src_path and not src_audio_path:
+        if task_norm in ("lego", "extract", "complete"):
+            raise ValueError(
+                f"Task '{task_norm}' requires backing/source audio. Please provide it in the Lego tab or Custom audio card."
+            )
         print(
             "[ACE] Audio2Audio / edit task requested but no reference audio "
             "was provided — falling back to plain text2music.",
@@ -612,6 +615,8 @@ def _prepare_reference_audio(
 
     if audio2audio_flag:
         ref_path = _ensure_reference_wav(src_audio_path)
+    elif task_norm in ("lego", "extract", "complete"):
+        ref_path = _ensure_reference_wav(src_audio_path)  # pipeline uses this as src_audio_path
     else:
         ref_path = None
 
@@ -825,11 +830,11 @@ def _run_ace_text2music(
     task: str = "text2music",
     repaint_start: float = 0.0,
     repaint_end: float = 0.0,
-    retake_variance: float = 0.5,
+    retake_variance: float = 0.2,  # MCP retake/repaint use 0.2
     src_audio_path: str | None = None,
-    # Audio2Audio + LoRA
+    # Audio2Audio + LoRA (ref_audio_strength 0.5 matches ACE-Step-MCP / pipeline default)
     audio2audio_enable: bool = False,
-    ref_audio_strength: float = 0.7,
+    ref_audio_strength: float = 0.5,
     lora_name_or_path: str | None = None,
     lora_weight: float = 0.75,
     cancel_check: Optional[Callable[[], bool]] = None,
@@ -972,10 +977,10 @@ def _run_ace_text2music(
 
         # Wire up reference vs source audio per ACE-Step pipeline:
         #
-        # - retake / cover / audio2audio: use ref_audio_input (pipeline sets task to
-        #   "audio2audio" and uses ref_latents). Do NOT pass src_audio_path.
-        # - repaint / extend: use src_audio_path (pipeline uses src_latents for the
-        #   segment to repaint or extend). Do NOT pass ref_audio_input for this path.
+        # - retake / cover / audio2audio / lego / extract / complete: use ref_audio_input so the pipeline
+        #   gets backing latents. For lego we use LOW ref_audio_strength (API default 0.3) so diffusion
+        #   starts from noisy backing and denoises toward the prompt (new instrument), matching timing.
+        # - repaint / extend: use src_audio_path (pipeline uses src_latents for repaint/extend segment).
         # - text2music: leave both unset (None).
         if not src_audio_path:
             call_kwargs["ref_audio_input"] = None
@@ -984,7 +989,7 @@ def _run_ace_text2music(
             call_kwargs["src_audio_path"] = src_audio_path
             call_kwargs["ref_audio_input"] = None
         else:
-            # retake (including cover/audio2audio from UI)
+            # retake, cover, audio2audio, lego, extract, complete: backing as ref (lego uses low ref_audio_strength)
             call_kwargs["ref_audio_input"] = src_audio_path
             call_kwargs["src_audio_path"] = None
 
@@ -1117,9 +1122,9 @@ def generate_track_ace(
     task: str = "text2music",
     repaint_start: float = 0.0,
     repaint_end: float = 0.0,
-    retake_variance: float = 0.5,
+    retake_variance: float = 0.2,  # ACE-Step-MCP retake/repaint default
     audio2audio_enable: bool = False,
-    ref_audio_strength: float = 0.7,
+    ref_audio_strength: float = 0.5,  # ACE-Step-MCP / pipeline default
     src_audio_path: str | None = None,
     lora_name_or_path: str | None = None,
     lora_weight: float = 0.75,
@@ -1219,7 +1224,7 @@ def generate_track_ace(
     if cfg_type not in ("apg", "cfg", "cfg_star"):
         cfg_type = "apg"
 
-    # Normalise edit / Audio2Audio settings before we talk to ACE-Step.
+    # Normalise edit / Audio2Audio (maps to ACE-Step task_type, ref_audio_input, src_audio, audio_cover_strength).
     task, audio2audio_enable, src_audio_path = _prepare_reference_audio(
         task,
         bool(audio2audio_enable),

docs/ACEFORGE_API.md

@@ -395,9 +395,11 @@ def flush(self):
         preferences_bp,
         ace_step_models_bp,
     )
+    from api.generate import reset_generation_queue
     app.register_blueprint(auth_bp, url_prefix="/api/auth")
     app.register_blueprint(songs_bp, url_prefix="/api/songs")
     app.register_blueprint(generate_bp, url_prefix="/api/generate")
+    reset_generation_queue()
     app.register_blueprint(playlists_bp, url_prefix="/api/playlists")
     app.register_blueprint(users_bp, url_prefix="/api/users")
     app.register_blueprint(contact_bp, url_prefix="/api/contact")

generate_ace.py

@@ -0,0 +1,45 @@
+#!/bin/bash
+# ---------------------------------------------------------------------------
+#  AceForge - Run locally for testing (no .app bundle)
+#  Builds the React UI if needed, then starts the Flask server at http://127.0.0.1:5056
+#
+#  Prerequisites:
+#    - Python 3.11 and dependencies. Easiest: run ./build_local.sh once to create
+#      venv_build and install deps; then use this script. Or create a venv and:
+#      pip install -r requirements_ace_macos.txt (plus TTS/ACE-Step as in build_local.sh).
+#    - Bun (only if ui/dist is missing): https://bun.sh
+#
+#  Optional:
+#    ACEFORGE_SKIP_UI_BUILD=1  - Skip UI build; use existing ui/dist/
+# ---------------------------------------------------------------------------
+
+set -e
+APP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$APP_DIR"
+
+# Build UI if needed
+UI_DIR="${APP_DIR}/ui"
+if [ -f "$UI_DIR/package.json" ] && [ -z "${ACEFORGE_SKIP_UI_BUILD}" ]; then
+    if [ ! -f "$UI_DIR/dist/index.html" ]; then
+        if ! command -v bun &> /dev/null; then
+            echo "ERROR: ui/dist missing and Bun not found. Install Bun (https://bun.sh) or run: ./scripts/build_ui.sh"
+            exit 1
+        fi
+        echo "[Run] Building UI..."
+        "${APP_DIR}/scripts/build_ui.sh"
+    fi
+fi
+
+# Prefer venv from full build
+VENV_PY="${APP_DIR}/venv_build/bin/python"
+if [ -x "$VENV_PY" ]; then
+    PY="$VENV_PY"
+    echo "[Run] Using venv_build"
+else
+    PY="python3"
+    echo "[Run] Using system python3 (install deps in a venv if you see ModuleNotFoundError)"
+fi
+
+echo "[Run] Starting AceForge at http://127.0.0.1:5056"
+echo ""
+exec "$PY" music_forge_ui.py