Fix audio_cover_strength in reference mode, lm_negative_prompt default, ace-understand binary, and metadata persistence

.env.example

@@ -22,6 +22,7 @@ MODELS_DIR=./models
 # Override individual binary paths only if they live outside ./bin/:
 # ACE_QWEN3_BIN=/path/to/ace-qwen3
 # DIT_VAE_BIN=/path/to/dit-vae
+# ACE_UNDERSTAND_BIN=/path/to/ace-understand
 #
 # Override the primary DiT GGUF only if you want a non-default model:
 # ACESTEP_MODEL=/path/to/models/acestep-v15-turbo-Q8_0.gguf

build.bat

@@ -118,7 +118,7 @@ if %ERRORLEVEL% NEQ 0 ( echo cmake build failed & exit /b 1 )
 :: Copy binaries
 if not exist "%BIN_DIR%" mkdir "%BIN_DIR%"
 set COPIED=0
-for %%N in (ace-qwen3 dit-vae neural-codec) do (
+for %%N in (ace-qwen3 dit-vae ace-understand neural-codec) do (
     set FOUND=
     for /r "%BUILD_DIR%" %%F in (%%N.exe) do (
         if exist "%%F" if "!FOUND!"=="" set FOUND=%%F

build.sh

@@ -137,7 +137,7 @@ cmake --build "$BUILD_DIR" --parallel
 # ── Copy binaries to bin/ ─────────────────────────────────────────────────────
 mkdir -p "$BIN_DIR"
 copied=0
-for name in ace-qwen3 dit-vae neural-codec; do
+for name in ace-qwen3 dit-vae ace-understand neural-codec; do
     found=$(find "$BUILD_DIR" -name "$name" -type f 2>/dev/null | head -1)
     if [ -n "$found" ]; then
         cp "$found" "$BIN_DIR/$name"

components/CreatePanel.tsx

@@ -205,7 +205,7 @@ export const CreatePanel: React.FC<CreatePanelProps> = ({
   const [lmCfgScale, setLmCfgScale] = useState<number>(savedSettings.lmCfgScale ?? 2.2);
   const [lmTopK, setLmTopK] = useState<number>(savedSettings.lmTopK ?? 0);
   const [lmTopP, setLmTopP] = useState<number>(savedSettings.lmTopP ?? 0.92);
-  const [lmNegativePrompt, setLmNegativePrompt] = useState<string>(savedSettings.lmNegativePrompt ?? 'NO USER INPUT');
+  const [lmNegativePrompt, setLmNegativePrompt] = useState<string>(savedSettings.lmNegativePrompt ?? '');
 
   // Expert Parameters (now in Advanced section)
   // Note: audio URLs are NOT persisted — they may point to deleted/temporary files
@@ -1033,7 +1033,12 @@ export const CreatePanel: React.FC<CreatePanelProps> = ({
     setUnderstandResult(prev => ({ ...prev, [target]: null }));
     setUnderstandError(prev => ({ ...prev, [target]: null }));
     try {
-      const result = await generateApi.understandAudioUrl(audioUrl, token);
+      // Use ID-based endpoint for uploaded reference tracks so the result is
+      // persisted to the database alongside the track record.
+      const matchingTrack = referenceTracks.find(t => t.audio_url === audioUrl);
+      const result = matchingTrack
+        ? await generateApi.understandReferenceTrack(matchingTrack.id, token)
+        : await generateApi.understandAudioUrl(audioUrl, token);
       setUnderstandResult(prev => ({ ...prev, [target]: result }));
       setUnderstandStatus(prev => ({ ...prev, [target]: 'done' }));
     } catch (err) {
@@ -1727,6 +1732,23 @@ export const CreatePanel: React.FC<CreatePanelProps> = ({
                   </>
                 )}
 
+                {/* Reference audio cover-strength slider (shown when a reference audio is loaded) */}
+                {audioTab === 'reference' && referenceAudioUrl && (
+                  <div className="flex items-center gap-2">
+                    <label className="text-[10px] text-zinc-500 dark:text-zinc-400 whitespace-nowrap">{t('audioCoverStrength')}</label>
+                    <input
+                      type="range"
+                      min="0"
+                      max="1"
+                      step="0.05"
+                      value={audioCoverStrength}
+                      onChange={(e) => setAudioCoverStrength(Number(e.target.value))}
+                      className="flex-1 h-1.5 accent-emerald-500"
+                    />
+                    <span className="text-[10px] text-zinc-400 tabular-nums w-7 text-right">{audioCoverStrength.toFixed(2)}</span>
+                  </div>
+                )}
+
                 {/* Source/Cover Audio Player */}
                 {audioTab === 'source' && sourceAudioUrl && (
                   <>
@@ -2007,6 +2029,15 @@ export const CreatePanel: React.FC<CreatePanelProps> = ({
                             <span className="text-[10px] text-zinc-400 tabular-nums">{formatTime(sourceDuration)}</span>
                           </div>
                         </div>
+                        <button
+                          type="button"
+                          onClick={() => void handleUnderstand('source', sourceAudioUrl)}
+                          disabled={understandStatus.source === 'running'}
+                          title={t('understandTooltip')}
+                          className="p-1.5 rounded-full hover:bg-zinc-200 dark:hover:bg-white/10 text-zinc-400 hover:text-violet-600 dark:hover:text-violet-400 transition-colors disabled:opacity-50"
+                        >
+                          {understandStatus.source === 'running' ? <Loader2 size={13} className="animate-spin" /> : <Sparkles size={13} />}
+                        </button>
                         <button
                           type="button"
                           onClick={handleClearSourceAudio}
@@ -2015,6 +2046,35 @@ export const CreatePanel: React.FC<CreatePanelProps> = ({
                           <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12"/></svg>
                         </button>
                       </div>
+                      {/* Understand result panel (lego source) */}
+                      {understandStatus.source !== 'idle' && (
+                        <div className={`rounded-lg px-3 py-2 text-[11px] space-y-1 ${
+                          understandStatus.source === 'error'
+                            ? 'bg-red-50 dark:bg-red-900/20 text-red-700 dark:text-red-400'
+                            : 'bg-violet-50 dark:bg-violet-900/20 text-violet-800 dark:text-violet-300'
+                        }`}>
+                          {understandStatus.source === 'running' && <span className="flex items-center gap-1"><Loader2 size={11} className="animate-spin" /> {t('understandRunning')}</span>}
+                          {understandStatus.source === 'error' && <span>{t('understandError')}: {understandError.source}</span>}
+                          {understandStatus.source === 'done' && understandResult.source && (
+                            <>
+                              <div className="font-semibold">{t('understandResult')}</div>
+                              {understandResult.source.caption && <div className="truncate opacity-80">🎵 {String(understandResult.source.caption).slice(0, 80)}{String(understandResult.source.caption).length > 80 ? '…' : ''}</div>}
+                              <div className="flex flex-wrap gap-2 opacity-70">
+                                {understandResult.source.bpm && <span>BPM: {String(understandResult.source.bpm)}</span>}
+                                {understandResult.source.keyscale && <span>Key: {String(understandResult.source.keyscale)}</span>}
+                                {understandResult.source.duration && <span>Duration: {Math.round(Number(understandResult.source.duration))}s</span>}
+                              </div>
+                              <button
+                                type="button"
+                                onClick={() => applyUnderstandResult(understandResult.source!)}
+                                className="mt-1 px-2 py-0.5 rounded bg-violet-600 text-white text-[10px] font-medium hover:bg-violet-700 transition-colors"
+                              >
+                                {t('understandApply')}
+                              </button>
+                            </>
+                          )}
+                        </div>
+                      )}
                       </>
                     )}
 

server/src/db/migrate.ts

@@ -158,6 +158,32 @@ function migrate(): void {
       throw error;
     }
   }
+
+  // Incremental column additions — ALTER TABLE in SQLite does not support
+  // IF NOT EXISTS, so we catch the error when the column already exists.
+  const columnMigrations: Array<{ sql: string; description: string }> = [
+    {
+      sql: 'ALTER TABLE reference_tracks ADD COLUMN understand_metadata TEXT',
+      description: 'Add understand_metadata column to reference_tracks',
+    },
+  ];
+
+  for (const { sql, description } of columnMigrations) {
+    try {
+      db.exec(sql);
+      console.log(`Migration applied: ${description}`);
+    } catch (err) {
+      const msg = String(err);
+      // better-sqlite3 reports duplicate columns as:
+      //   "table X already has column Y"
+      if (msg.includes('already has column') || msg.includes('duplicate column name') || msg.includes('already exists')) {
+        // Column already present — nothing to do
+      } else {
+        console.error(`Migration failed: ${description}`, err);
+        throw err;
+      }
+    }
+  }
 }
 
 // Run migrations

server/src/routes/referenceTrack.ts

@@ -351,6 +351,19 @@ router.post('/:id/understand', understandRateLimiter, authMiddleware, async (req
 
     const audioUrl = `/audio/${result.rows[0].storage_key}`;
     const understood = await runUnderstand(audioUrl);
+
+    // Persist the understand result alongside the track record so it survives
+    // page reloads and can be reused without re-running the (expensive) analysis.
+    // This is best-effort — a save failure doesn't invalidate the result.
+    try {
+      await pool.query(
+        'UPDATE reference_tracks SET understand_metadata = $1 WHERE id = $2',
+        [JSON.stringify(understood), req.params.id]
+      );
+    } catch (saveErr) {
+      console.warn('Understand metadata save failed (non-fatal):', saveErr);
+    }
+
     res.json(understood);
   } catch (error) {
     const msg = error instanceof Error ? error.message : 'Failed to understand audio';

server/src/services/acestep.ts

@@ -617,6 +617,15 @@ async function runViaSpawn(
       requestJson.lm_top_k           = params.lmTopK           ?? 0;
       requestJson.lm_negative_prompt = params.lmNegativePrompt || '';
       requestJson.use_cot_caption    = params.useCotCaption    ?? true;
+
+      // Reference audio for style-guided text-to-music generation.
+      // When the user selects a reference track, pass it to dit-vae via the
+      // request JSON so the binary can condition the synthesis on that audio.
+      if (params.referenceAudioUrl) {
+        const refAudioPath = resolveAudioPath(params.referenceAudioUrl);
+        requestJson.reference_audio       = refAudioPath;
+        requestJson.audio_cover_strength  = params.audioCoverStrength ?? 1.0;
+      }
     }
 
     const requestPath = path.join(tmpDir, 'request.json');