docs/UPLOAD_ERROR_AND_RUNTIME_FALLBACK.md

Upload, visible errors, and runtime fallback

Last updated: 2026-05-12

Problem addressed

A deployed UI could appear broken before a file was even processed:

• the default error banner was visible with placeholder text because CSS overrode the HTML hidden attribute;
• the upload affordance was too subtle because the middle top-bar control looked like passive text;
• if a user selected a file before /api/config finished loading, automatic extraction could start with incomplete control defaults;
• a Spleeter-default runtime without Spleeter installed could fail or escalate into a slower backend instead of staying usable.

Current behavior

• The error banner is hidden by default via an explicit [hidden] CSS rule.
• Errors shown in the UI include the request path, HTTP status, and server detail/traceback when available.
• The top bar now contains a visible Choose audio button plus whole-app drag/drop.
• File selection waits for backend config before submitting /api/jobs.
• /api/config exposes runtime diagnostics for optional separation engines.
• Spleeter remains the configured default, but if the runtime does not have Spleeter available the UI switches the default control to full-mix mode so the app still works.
• Backend Spleeter failures with fallback enabled now fall back to full-mix processing, not automatic full-track Demucs. Demucs is an explicit quality option.

Rationale

The normal user path should be reliable even on minimal hosted runtimes. Full-mix extraction is less clean than source-separated extraction, but it is fast, dependency-light, and visibly produces cards. Demucs remains available for deliberate high-quality separation, but it is too expensive and unpredictable as a silent automatic fallback for a simple drop-to-process UI.

Validation

Covered by:

python3 scripts/test_upload_error_visibility_and_fallback.py

The script checks:

• runtime diagnostics are exposed by /api/config;
• invalid upload extensions produce actionable 400 details;
• Spleeter failure falls back to full-mix extraction without attempting Demucs.