# 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:

```bash
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.