[thcp]

Refs #405

What changes for the person running setup

• The model step says which model it is on: "Getting AI model 2 of 5: beat detection... Elapsed: 12s." It used to show three timed messages.
• A Skip: download each model when first needed button appears once the first model starts. Skipping stops the download at once, and the wizard goes on to start StemDeck.
• Before the wizard leaves the page, it says what did not arrive and waits for Continue:
  • Skipped: "AI model download skipped, so these were not downloaded: beat detection, song sections, ... StemDeck works without them: each one downloads the first time a feature needs it." If the separation model is among them, it adds: "so the first separation downloads the separation model before it starts."
  • Offline: "StemDeck could not reach the model download servers (no internet connection, or the connection stopped answering), so these AI models were not downloaded: ..." A model that failed for another reason is listed separately, with a pointer to logs/setup.log.
  • Disk too full: "Not enough free disk space for the AI models: about 1.8 GB needed, 0.4 GB free, so none was downloaded. ..."
  • Before this, a missing model only reached the browser console. The first sign was a feature that quietly did less.
• Closing the window during the model download now closes it. On Windows it used to hang until the download ended or hit the 30-minute limit.
• A dead connection now ends each model on its own:
  • The separation and beat models end in about 1.5 minutes.
  • The other models end at their own library's limit.
  • The next model still gets its turn.
• A slow, healthy download is no longer killed at 30 minutes.

Why, and how it works

• The hang on close.
  • warmup_models was a blocking Tauri command. Tauri runs those on the main thread: see tauri-macros 2.6.0, body_blocking, and the Tauri docs. reveal_saved already avoids this for the same reason.
  • So for the whole download the window could not handle a close, and no other command could reach the shell, Skip included.
  • It is now async and does its work in spawn_blocking.
• The child left running on Windows.
  • stop_backend only signalled the setup child on unix.
  • The state now holds the setup child's label and, on Windows, its job (from fix(desktop): keep the portable WebView2 profile in data, end setup children with the app #897). Stopping it calls TerminateJobObject, which ends the warmup and anything it started.
  • skip_model_warmup only stops the setup child when that child is the model warmup. A stray call can never cut a pip install short.
  • Only one setup child runs at a time: run_setup_child refuses a second one. Without that, two children would share the one slot that stops them.
• The deadline.
  • The warmup is now waited on with child_output_streaming: 6 minutes of silence, with a 2-hour cap. It used to be a fixed 30 minutes.
  • Output on stderr now also counts as activity in that reader. The downloads report progress there (tqdm), and the warmup's stdout stays quiet for as long as one model takes.
  • For pip, this can only make the stall budget more lenient. Its cap is unchanged.
  • Why 6 minutes: I ran the real warmup behind a proxy that never answers. Both streams went quiet for 300 s at most (audio-separator's own read timeout) and for 77 s at most anywhere else.
• app/pipeline/warmup.py.
  • Every model runs inside bounded_downloads from fix(separate): bound the separation model download and say why it failed #905:
    • torch.hub downloads get the read timeout and the retries.
    • Sockets that set no timeout of their own get the read timeout. That covers Whisper's.
  • New stdout lines:
    • WARMUP_START <model> <n> <count> before each model. The shell passes it on as a model-warmup-progress event.
    • WARMUP_OFFLINE <model> after a failure whose cause chain holds a DNS failure, a timeout, or a refused or dropped connection.
    • WARMUP_NO_SPACE <needed> <free> when the disk cannot hold the models. Nothing downloads after it.
  • The space check:
    • It adds up each model's size, measured on a finished install, and subtracts what the models folder already holds. So a second setup run on a nearly full disk is not refused.
    • A check that cannot run is logged and does not stop the downloads.
• A half-downloaded file after Skip. Checked per library:
  • torch.hub (separation and beat models) writes to a .partial name and moves the file into place only once it is whole. Tested.
  • The Hugging Face hub (sections) writes to an .incomplete file and renames it. Checked by reading its source.
  • Whisper checks the file's SHA-256 on every load.
  • The vocal-split model loads through load_or_heal. It now also heals audio-separator's download_checks.json, which is written in place and was not covered.
  • load_or_heal now clears the failed load's frames before it deletes anything. audio-separator reads its indexes with json.load(open(...)) and leaves the file open, and Windows will not delete an open file. That also makes the existing index healing ([Bug]: Stuck First Launch #502) work on Windows.

How it was verified

Red then green: I ran each new test against the old code first.

• cargo test (Windows), 223 passed:
  • closing_the_window_mid_setup_ends_the_setup_child failed on the old code ("the setup child ran on for 20.2s") and now passes.
  • output_on_stderr_alone_keeps_a_streamed_child_alive failed on the old code ("timed out after 3 seconds with no output") and now passes.
  • Also new:
    • skip_stops_the_model_warmup_and_nothing_else
    • a_second_setup_child_is_refused_while_one_runs
    • the status and progress parsers
    • the stall budget bound
• tests/test_pipeline_warmup.py:
  • 7 of the new or changed tests failed on the old warmup.
  • One of them is test_a_stalled_model_host_ends_the_model_instead_of_the_step. Old code: a host that never answers held the step for 20 s, until the test server gave up. New code: under 10 s, then the next model runs.
  • test_a_download_stopped_midway_leaves_no_file_that_looks_complete hard-kills a real warmup process in the middle of a download from a throttled local server. It checks that only a .partial file is left, and that the next try downloads the whole file.
• tests/test_model_cache.py::test_a_half_written_vocal_split_index_is_fetched_again drives audio-separator's own index reader against a half-written download_checks.json.
  • Old code: JSONDecodeError, every time.
  • With the file listed but the frames not cleared: PermissionError on Windows.
  • Now: the file is fetched again and read.
• The Python tests use local servers on throwaway ports and a fake free-space function. Proxies are switched off for them. There is no real network and no real model.
• End to end with the real libraries and no real network:
  • I ran python -m app.pipeline.warmup behind a proxy on a closed local port. All four models that need a download reported WARMUP_FAILED then WARMUP_OFFLINE. The run took 86 s and left no file behind.
  • Behind a proxy that accepts and never answers, every model failed on its own and was reported offline, and the run still reached the last model. It took 758 s, with the stream silences above.
• tests/e2e/setup-wizard.spec.mjs (new):
  • It serves desktop/ui with a stand-in Tauri bridge.
  • It covers the progress line, Skip and its notice, offline versus other failures, the no-space notice, and going straight on when every model arrived.
  • 3 of the first 4 tests failed on the old wizard.
• Also run: cargo fmt --check, cargo clippy --tests -- -D warnings on Windows, ruff check and format, and the full pytest suite.
• Not compiled here: the Linux and macOS cfg(unix) lines. The PR's Rust check jobs cover them.

Guide and languages

No Guide entry and no i18n change. The setup wizard (desktop/ui) runs before the backend exists, is English-only, and is not part of the in-app Guide. No control in static/js changed.

Update path

• Changes the desktop shell (Rust), so it needs a new binary, not a payload-only update.
• Does not touch uv.lock.

Not changed here

• ensure_torch_device and repair_torchvision are blocking commands too, so the GPU step holds the main thread in the same way.
• Their pip progress events therefore probably reach the screen only when they end. Not verified on a running app.
• Fixing them is the same change as here: make them async and use spawn_blocking. It is left for its own PR, so this one stays about the model step.

What needs a human

Run one clean first-run setup on Windows with a throttled network, in a throwaway data folder. No automated test here drives a real WebView2, so these need a person:

1. Unzip the portable build into a new folder, with no data folder next to it.
2. Throttle the network, for example with NetLimiter at 100 KB/s for StemDeck's python.exe, or use a slow hotspot.
3. Start StemDeck. At the model step, check that the line names each model in turn ("Getting AI model 1 of 5: stem separation...").
4. Close the window during the download. It should close within a few seconds, and no python.exe from that folder should remain in Task Manager.
5. Start again and press Skip while the line says model 1 of 5. The notice should name the models that were not downloaded. Press Continue: StemDeck should open, and the first Split should show "Downloading the separation model N%".